Developer CD Series 1992 June: ROMin Holiday/ADC Developer CD (1992-06) (''ROMin Holiday'')_iso/Developer Connection - 06-1992.iso/Developer Essentials/DTS Sample Code/System 7.0 Samples/DTS.Utilities/Utilities.p

Text File | 1991-02-14 | 22.6 KB | 513 lines | [TEXT/MPS ]

{-------------------------------------------------------------------------------------------
#
#    Apple Macintosh Developer Technical Support
#
#    Collection of Utilities for DTS Sample code
#
#    Program:    Utilities.p.o
#    File:        Utilities.p -    Pascal Interface
#
#    Copyright © 1988-1990 Apple Computer, Inc.
#    All rights reserved.
#
-------------------------------------------------------------------------------------------}
{[j=20/53/1$] Pasmat Options}

UNIT Utilities;

    INTERFACE

        USES
            { Type 1 }
            Types, QuickDraw,

            { Type 2 }
            Controls, Events, FixMath, Fonts, Memory, Menus, OSUtils, Resources, SegLoad,
            TextEdit, ToolUtils, Traps, SysEqu,
{$IFC MPW32}
            {$U $$Shell(PInterfaces)GestaltEqu} GestaltEqu, { Use standard interface }
            {$U $$Shell(PInterfaces)Folders} Folders,         { Use standard interface }
{$ELSEC}
            GestaltEqu,        { Use the one in the Utilities directory }
            Folders,        { Use the one in the Utilities directory }
{$ENDC}

            { Type 3 }
            Desk, Files, OSEvents, Script, Windows,

            { Type 4 }
            Dialogs,

            { Type 5 }
            Packages;

        CONST
            kUseCreatorString    = - 1;                { Pass this to StandardAbout if you would
                                                     like the string stored in your creator
                                                     resource to appear in the about box. }
            kUseRealAppName     = - 2;                { Pass this to StandardAbout if you would
                                                     like the name of your application to
                                                     appear in the about box. }

            rUtilErrorAlert     = 256;                { dlg ID used in ErrorAlert }
            rUtilErrorMessageAlert = 257;            { dlg ID used in ErrorAlertMessage }
            rStdAboutAlert         = 258;                { dlg ID used for About box. }

            rUtilStrings        = 256;                { STR# resource we use for errors. }
            eStandardErr        = 1;                { Generic "An error occured" string. }
            eNoMenuBar            = 2;                { "No 'MBAR' resource was found." }

            kButtonFrameSize    = 3;                { button frame’s pen size }
            kButtonFrameInset    = - 4;                { inset rectangle adjustment around
                                                     button }
            kOSEvent            = app4Evt;            { event used by MultiFinder }
            kSuspendResumeMessage = 1;                { high byte of suspend/resume event
                                                     message }
            kResumeMask         = 1;                { bit of message field for resume vs.
                                                     suspend }
            kMouseMovedMessage    = $FA;                { high byte of mouse-moved event message }
            kNoEvents            = 0;                { no events mask }

            kExtremeNeg         = - 32768;            { kExtremeNeg and kExtremePos are used to
                                                     set up wide open rectangles and
                                                     regions. }
            kExtremePos         = 32767 - 1;        { required for old region bug }

            kOffscreenLoc        = $4000;

            kDITop                = $0050;            { kDITop and kDILeft are used to locate
                                                     the Disk Initialization dialogs. }
            kDILeft             = $0070;

            kControlInvisible    = 0;
            kControlVisible     = $FF;                {kControlInvisible is used to 'turn off'
                                                     controls (i.e., cause the control not to be
                                                     redrawn as a result of some Control Manager
                                                     call such as SetCtlValue) by being put into
                                                     the contrlVis field of the record.
                                                     kControlVisible is used the same way to 'turn
                                                     on' the control.}

            kCntlActivate        = 0;                { enabled control’s hilite state }
            kCntlDeactivate     = $FF;                { disabled control’s hilite state }
            kCntlOn             = 1;                { control’s value when truned on }
            kCntlOff            = 0;                { control’s value when truned off }
            kSelect             = 1;                { select the control }
            kDeselect            = 0;                { deselect the control }

            kScrollbarWidth     = 16;                { kScrollBarWidth can be used in
                                                     calculating values for control
                                                     positioning and sizing.}
            kScrollbarAdjust    = kScrollbarWidth - 1;

            kDelayTime            = 8;                { For the delay time when flashing the
                                                     menubar and highlighting a button.
                                                     8/60ths of a second}

            kStartPtH            = 2;                { offset from the left of the screen }
            kStartPtV            = 2;                { offset from the top of the screen }
            kStaggerH            = 16;                { staggering amounts for new windows }
            kStaggerV            = 22;

            chBackspace         = CHR(8);            { ASCII code for Backspace character }
            chClear             = CHR(27);            { ASCII code for Clear key (aka ESC) }
            chDown                = CHR(31);            { ASCII code for down arrow }
            chEnd                = CHR(4);            { ASCII code for the End key }
            chEnter             = CHR(3);            { ASCII code for Enter character }
            chEscape            = CHR(27);            { ASCII code for Escape (aka Clear) key }
            chFunction            = CHR(16);            { ASCII code for any function key }
            chFwdDelete         = CHR($7F);         { ASCII code for forward delete }
            chHelp                = CHR(5);            { ASCII code for Help key }
            chHome                = CHR(1);            { ASCII code for the Home key }
            chLeft                = CHR(28);            { ASCII code for left arrow }
            chPageDown            = CHR(12);            { ASCII code for Page Down key }
            chPageUp            = CHR(11);            { ASCII code for Page Up key }
            chReturn            = CHR(13);            { ASCII code for Return character }
            chRight             = CHR(29);            { ASCII code for right arrow }
            chSpace             = CHR(32);            { ASCII code for Space character }
            chTab                = CHR(9);            { ASCII code for Tab character }
            chUp                = CHR(30);            { ASCII code for up arrow }

            { Define these for gQDVersion }
            kQDOriginal            = 0;                { Original QuickDraw }
            kQD8Bit                = 1;                { 8-bit Color QuickDraw }
            kQD32Bit            = 2;                { 32-bit QuickDraw }

        TYPE

        { Various handy types for type coercion. For instance, you can take a handle,
          cast it into a RectHandle, dereference it twice, and get a Rect. I.e.,

            myRect := RectHandle(someHandle)^^;

          Of course, this assumes that you know there is a valid rectangle at that
          location in the block of data referenced by the handle. }

        { Some of these are now defined in MPW 3.2 }
{$IFC NOT MPW32}
            IntegerPtr            = ^INTEGER;
{$ENDC}
            IntegerHandle        = ^IntegerPtr;

{$IFC NOT MPW32}
            LongIntPtr            = ^LONGINT;
{$ENDC}
            LongIntHandle        = ^LongIntPtr;

            BooleanPtr            = ^BOOLEAN;
            BooleanHandle        = ^BooleanPtr;

            SignedBytePtr        = ^SignedByte;
            SignedByteHandle    = ^SignedBytePtr;

            RectHandle            = ^RectPtr;

            WindowPeekPtr        = ^WindowPeek;

            { This is the template to the WIND resource. }

            WindowTemplate        = RECORD            {template to a WIND resource}
                boundsRect:         Rect;
                procID:             INTEGER;
                visible:            BOOLEAN;
                filler1:            BOOLEAN;
                goAwayFlag:         BOOLEAN;
                filler2:            BOOLEAN;
                refCon:             LONGINT;
                title:                Str255;
                END;
            WindowTPtr            = ^WindowTemplate;
            WindowTHndl         = ^WindowTPtr;

            TwoIntsMakesALong    = RECORD            {build a signed LONGINT...}
                CASE INTEGER OF                     {...from an unsigned INTEGER}
                    1:
                        (long:                 LONGINT);
                    2:
                        (ints:                 ARRAY [0..1] OF INTEGER);
                END;                                {TwoIntsMakesALong}

        VAR

        { The following global variables are initialized by StardardInitialization to
            define the environnment.  This used to be a single SysEnvRec, but now,
            all those variables defined in a SysEnvRec can be returned by Gestalt
            (except sysVRefNum; see FindSysFolder).  Note that all the variables
            below will be correctly initialized whether Gestalt is available or not;
            the Gestalt glue handles this. }

            gMachineType:        INTEGER;            {which machine this is}
            gSystemVersion:        INTEGER;            {System version number}
            gProcessorType:        INTEGER;            {which CPU this is}
            gHasFPU:            BOOLEAN;            {true if machine has an FPU}
            gQDVersion:            INTEGER;            {major QD version #; 0 for original,
                                                        1 for color QD, 2 for 32-bit QD}
            gKeyboardType:        INTEGER;            {which type of keyboard is present}
            gAppleTalkVersion:    INTEGER;            {AppleTalk version number}

        { These are also handled by Gestalt. gHasPMMU has no corresponding SysEnvRec
            field, but it is handled by the glue, so we include it here for completeness.
            gAUXVersion will be initialized with Gestalt if present, but correctly
            set even if Gestalt is not available}
            gHasPMMU:            BOOLEAN;            {true if machine has a PMMU or equivalent}
            gAUXVersion:        INTEGER;            {major A/UX version number (0 if not present)}

        { gHasWaitNextEvent is set to TRUE if the Macintosh we are running on has
          WaitNextEvent implemented. We can use this in our main event loop to
          determine whether to call WaitNextEvent or GetNextEvent. }

            gHasWaitNextEvent:    BOOLEAN;            {set up by StandardInitialization}

        { gAppResRef is the application’s resource file reference. I need to save
          this since I can open other resource files. The current resource file is
          always gAppResRef unless I momentarily set it to another file to read its
          resources, and then immediately restore it back.}

            gAppResRef:         INTEGER;            {set up by StandardInitialization}

        { gInBackground is maintained by our osEvent handling routines. Any part of
          the program can check it to find out if it is currently in the background.}

            gInBackground:        BOOLEAN;            {maintained by StandardInitialization and
                                                     DoEvent}

        { gAppName holds the name of the application that's running. You can use if
          for any purpose you'd like. It is also used by StandardAbout if it can't
          find a string to use for the application name in a resource, so make sure
          you call InitForStandardAbout if you are going to call StandardAbout. If you
          call StandardInitialization, this is done for you. }

            gAppName:            Str255;

        { gSignature holds the creator signature for the running application. It follows the
          same rules as those for gAppName. }

            gSignature:            OSType;

        { Initial values of these global variables are set to zero or FALSE by MPW's
          runtime initialization routines.  If the Utilities initialization routines
          have been properly called, then gUtilitiesInited will be true.  If it is
          not true, then the values of the above global variables are invalid. }

            gUtilitiesInited:    BOOLEAN;

        FUNCTION CenteredAlert(alertID: INTEGER; relatedWindow:WindowPtr): INTEGER;
        { Given an Alert ID and a related window pointer, this routine will center
          the alert on the same device as the related window.  If the related
          window pointer is nil, then the alert will be centered on the device
          that the alert would normally be placed if Alert was called directly. }

        PROCEDURE CenterRectInRect(outerRect: Rect; VAR innerRect: Rect);
        { Given two rectangles, this routine centers the second one within the first. }

        FUNCTION CenterWindow(window:WindowPtr; relatedWindow:WindowPtr): Rect;
        { Given a window pointer and a related window pointer, this routine will
          center the window on the same device as the related window.  If the
          related window pointer is nil, then the window will be centered on the
          device that the window already is.
          WARNING: This routine may move or purge memory. }

        PROCEDURE CloseAnyWindow(window: WindowPtr);
        { Closes the indicated window.  Does the right thing, taking into account
          that the window may belong to a DA.
          WARNING: An application window is closed via a CloseWindow call.  Use
                       this call when you want to keep the storage for the window
                    record.  (Compare against DisposeAnyWindow.) }

        PROCEDURE DisposeAnyWindow(window: WindowPtr);
        { Closes the indicated window.  Does the right thing, taking into account
          that the window may belong to a DA.
          WARNING: An application window is closed via a DisposeWindow call.  Use
                       this call when you want to free up the storage for the window
                    record.  (Compare against CloseAnyWindow.) }

        PROCEDURE DeathAlert(errResID: INTEGER; errStringIndex: INTEGER);
        { Display an alert that tells the user an error occurred, then exit the
          program. This routine is used as an ultimate bail-out for serious errors
          that prohibit the continuation of the application. }

        PROCEDURE DeathAlertMessage(errResID, errStringIndex, message: INTEGER);

        PROCEDURE ErrorAlert(errResID, errStringIndex: INTEGER);

        PROCEDURE ErrorAlertMessage(errResID, errStringIndex, message: INTEGER);

        FUNCTION FindSysFolder (VAR foundVRefNum: INTEGER; VAR foundDirID: LongInt): OSErr;
        { FindSysFolder returns the (real) vRefNum, and the DirID of the current
          system folder.  It uses the Folder Manager if present, otherwise
          it falls back to SysEnvirons.  It returns zero on success, otherwise
          a standard system error.}

        FUNCTION GetAppIndResource(theType: ResType;index: INTEGER; VAR err:OSErr): Handle;
        { GetAppIndResource gets a resource from the application's resource file by index }

        FUNCTION GetAppNamedResource(theType: ResType;name: Str255; VAR err:OSErr): Handle;
        { GetAppNamedResource gets a resource from the application's resource file by name }

        FUNCTION GetAppResource(theType:ResType; theID:INTEGER; VAR err:OSErr): Handle;
        { GetAppResource gets a resource from the application's resource file by resource ID }

        FUNCTION GetAUXVersion: INTEGER;

        FUNCTION    GetCenteredDialog(id:INTEGER; storage: Ptr;
            relWindow, behind:WindowPtr): DialogPtr;
        { Given a dialog ID and a related window pointer, this routine will center
          the dialog on the same device as the related window.  If the related
          window pointer is nil, then the dialog will be centered on the device
          that the dialog would normally be placed if GetNewDialog was called. }

        FUNCTION    GetCenteredWindow(id:INTEGER; storage: Ptr; relWindow, behind: WindowPtr;
            inColor:BOOLEAN): WindowPtr;
        { Given a window ID and a related window pointer, this routine will center
          the window on the same device as the related window.  If the related
          window pointer is nil, then the window will be centered on the device
          that the window would normally be placed if GetNewWindow was called. }

        FUNCTION GetCheckOrRadio(dlgPtr: DialogPtr; itemNo: integer): BOOLEAN;

        FUNCTION GetGestaltResult (gestaltSelector: OSType): LongInt;
        { GetGestaltResult returns the result value from Gestalt for the specified selector.
            If Gestalt returned an error GetGestaltResult returns zero.  Use of this function
            is only cool if we don't care whether Gestalt returned an error.  In many cases
            you may need to know the exact Gestalt error code so then this routine would be
            inappropriate.}

        FUNCTION GetGlobalMouse: Point;
        { Returns the location of the mouse in local coordinates. It does this by
          calling OSEventAvail. }

        FUNCTION GetGlobalTopLeft(window: WindowPtr): Point;
        { Given a window, this will return the top left point of the window’s port in
          global coordinates. Something this doesn’t include, is the window’s drag
          region (or title bar). This returns the top left point of the window’s
          content area only. }

        FUNCTION GetKFreeSpace(vRefNum: INTEGER): LONGINT;

        FUNCTION GetMainScreenRect: Rect;

        FUNCTION GetRectDevice(globalRect: Rect): GDHandle;
        { Find the greatest overlap device for the given global rectangle. }

        FUNCTION GetRectDeviceRect(globalRect: Rect): Rect;
        { Find the rect of the greatest overlap device for the given global rect. }

        FUNCTION    GetSomeKindOfWindow(FUNCTION whatKind(window, relWindow:WindowPtr):Rect;
            windID:INTEGER; storage: Ptr; relWindow, behind:WindowPtr; inColor:BOOLEAN):WindowPtr;
        { Given a window positioning procedure pointer, a window ID and a window
          pointer the window relates to, this function open a new window by either
          a NewCWindow or a NewWindow call, depending on the value of inColor.  The
          window will be opened invisible, independent of what the resource says.
          Once the window is opened successfully, the positioning procedure is
          called.  The positioning procedure is passed a pointer to the just-opened
          invisible window and a pointer to the related window.  It is up to the
          positioning procedure to move the invisible window to the correct location
          on the correct device.  Once the positioning procedure returns, the window
          will be made visible if so indicated by the resource. }

        FUNCTION    GetStaggeredWindow(id:INTEGER; storage: Ptr;
            relWindow,behind:WindowPtr; inColor:BOOLEAN):WindowPtr;
        { Given a window ID and a window pointer the window relates to, this function
          will stagger the window’s rectangle before showing it on the proper screen.
          This follows the Apple Human Interface Guidelines for where to place a
          staggered window on the screen.  If the window is not closely associated
          with another window, pass a nil for the window pointer of the related
          window.  If you pass a nil, the window is simply displayed where the
          resource would indicate. }

        FUNCTION GetTrapType(theTrap: INTEGER): TrapType;
        { Returns the type (OSType or ToolType) of the trap. It does this by checking
          the bits of the trap word. }

        FUNCTION GetWindowContentRect(window:WindowPtr):Rect;
        { Given a window pointer, return the global rectangle that encloses the
          content area of the window. }

        FUNCTION GetWindowCount(includeDAs,includeInvisibles:BOOLEAN):INTEGER;
        { This procedure counts the number of windows in the application plane.  You
          have the choices of also including DAs and invisible windows in this count. }

        FUNCTION GetWindowDevice(window:WindowPtr):GDHandle;
        { Find the greatest overlap device for the given window. }

        FUNCTION GetWindowDeviceRect(window:WindowPtr):Rect;
        { Given a window pointer, find the device that contains most of the window
          and return the device's bounding rectangle. }

        FUNCTION GetWindowDeviceRectNMB(window:WindowPtr):Rect;
        { Given a window pointer, find the device that contains most of the window
          and return the device's bounding rectangle.  If this device is the main
          device, then remove the menubar area from the rectangle. }

        FUNCTION GetWindowStructureRect(window:WindowPtr):Rect;
        { This procedure is used to get the rectangle that surrounds the entire
          structure of a window.  This is true whether or not the window is visible.
          If the window is visible, then it is a simple matter of using the bounding
          rectangle of the structure region.  If the window is invisible, then the
          strucRgn is not correct.  To make it correct, then window has to be moved
          way off the screen and then made visible.  This generates a valid strucRgn,
          although it is valid for the position that is way off the screen.  It still
          needs to be offset back into the original position.  Once the bounding
          rectangle for the strucRgn is obtained, the window can then be hidden again
          and moved back to its correct location.  Note that ShowHide is used,
          instead of ShowWindow and HideWindow.  HideWindow can change the plane of
          the window.  Also, ShowHide does not affect the hiliting of windows. }

        PROCEDURE GlobalToLocalRect(VAR aRect: Rect);

        PROCEDURE InitToolBox;

        PROCEDURE InitUtilities;
        { This sets up some global variables for use by the utilities package.  If you call
           StandardInitialization, you don't need to call this, as it will do it for you. }

        FUNCTION IsAppWindow(window: WindowPtr): BOOLEAN;
        { Returns TRUE if the windowKind of the window is greater than or equal to
          userKind. If it is less, or the window is NIL, then return FALSE. }

        FUNCTION IsDAWindow(window: WindowPtr): BOOLEAN;
        { Returns TRUE if the windowKind of the window is less than zero. If not, or
          the window is NIL, then return FALSE. }

        PROCEDURE LocalToGlobalRect(VAR aRect: Rect);

        FUNCTION LockHandleHigh(theHandle: UNIV Handle): SignedByte;
        { Does a MoveHHi on the handle and then locks it.  Also, the original state
          of the handle is returned, so you can keep it and set the handle back to it's
          original state with a HSetState call. }

        FUNCTION NumToolboxTraps: INTEGER;
        { Determines the size of the Tool trap table. It does this by sampling a
          couple of trap locations and seeing which, if any are Unimplemented. }

        PROCEDURE OutlineControl(button: UNIV ControlHandle);

        PROCEDURE OutlineDialogItem(dlgPtr: DialogPtr; item: integer);

        PROCEDURE PositionRectInRect(outerRect: Rect; VAR innerRect: Rect; horzRatio,vertRatio: Fixed);
        {  Given two rectangles, this routine positions the second within the first one
           so that the it maintains the spacing specified the the horzRatio and vertRatio
           parameters. In other words, to center an inner rectangle hoizontally, but
           have its center be 1/3 from the top of the outer rectangle, call this
           routine with horzRatio = FixRatio (1, 2), vertRatio = FixRatio (1, 3). }

        PROCEDURE PullApplicationToFront;

        PROCEDURE SelectButton(button: UNIV ControlHandle);
        {  Given the button control handle, this will cause the button to look as if it
           has been clicked in. This is nice to do for the user if they type return or
           enter to select the default item. }

        PROCEDURE SetCheckOrRadioButton(dlgPtr: DialogPtr; itemNo: INTEGER; state: INTEGER);

        FUNCTION StaggerWindow(window,relatedWindow:WindowPtr):Rect;
        { This algorithm for staggering windows does quite a good job.  It also is
          quite gnarly.  Here's the deal:
          There are pre-designated positions that we will try when positioning a
          window.  These slots will be tried from the upper-left corner towards the
          lower-right corner.  If there are other windows in that slot, then we will
          consider that slot taken, and proceed to the next slot.  A slot is
          determined to be taken by checking a point with a slop area.  This slop
          area is diamond-shaped, not simply rectangular.  If there is no other
          visible window with an upper-left corner within the slopt diamond, then
          we are allowed to position our window there.
          The above rule holds true unless this forces the window to be partly
          off the screen.  If the window ends up partly off the screen, then we give
          up and just put it in the first slot. }

        PROCEDURE StandardAbout(appNameStringID: INTEGER);
        { Shows a standard about box with the name of the application, its version
          number, a copyright notice, and DTS credits. Most of this information is
          taking from a standard DITL and the application’s 'vers' resource. The name
          of the application is taken either from the 'STR ' resource passed in to
          this routine, or from GetAppParms if that resource doesn’t exist, or you
          pass in -1. }

        PROCEDURE StandardInitialization(callsToMoreMasters: INTEGER);
        { Initializes “gInBackGround” to FALSE. Makes the following InitXXX calls:
          InitGraf, InitFonts, InitWindows, InitMenus, TEInit, InitDialogs,
          InitCursor. Brings application to front with 3 EventAvail calls.
          Initializes some variables using Gestalt. Calls TrapExists to initialize
          “gHasWaitNextEvent”. }

        PROCEDURE StandardMenuSetup(MBARID, AppleMenuID: INTEGER);
        { Installs and draws the menus indicated by 'MBAR'(MBARID). Adds DA’s to the
          menu indicated by AppleMenuID by calling AddResMenu. If the menuBar cannot
          be created, the alert specified by rDeathAlert is displayed. }

        PROCEDURE ToggleCheck(dlgPtr: DialogPtr; chkItem: integer);

        FUNCTION TrapExists(theTrap: INTEGER): BOOLEAN;
        { Returns TRUE if the trap exists (i.e., it’s callable without getting DS
          error 12) }

        PROCEDURE ZoomToWindowDevice(window:WindowPtr; maxWidth,maxHeight,zoomDir:INTEGER; front:BOOLEAN);

    IMPLEMENTATION

{$I Utilities.inc1.p}

END.